##############################################################################
###+---------+################################################################
#+-| F_FLUSH |--------------------------------------------+###################
#| +---------+ Writes any data in the file buffer to disk |###################
#+--------------------------------------------------------+###################
##############################################################################
##############################################################################
#+--| Summary |----------------+##############################################
#|     #INCLUDE fileio.hdr     |##############################################
#+-----------------------------+##############################################
##############################################################################
##############################################################################
#+--| Syntax |--------------------------+#####################################
#|     PROCEDURE f_flush PROTOTYPE      |#####################################
#|      PARAMETERS FILE file_stream     |#####################################
#+--------------------------------------+#####################################
##############################################################################
##############################################################################
########+---| Description |------------------------------------------+########
########| The f_flush procedure writes any data in the file buffer   |########
########| associated with file_stream to the disk file.  file_stream |########
########| must have been opened with &F_WRITE or &F_CREATE mode.     |########
########| ---------------------------------------------------------- |########
########| The text file is closed and then reopened to accomplish    |########
########| the flush.  This is because DOS does not directly write    |########
########| data to a disk file, i.e., it buffers its writes.          |########
########| To force the data to the disk, the file must be closed.    |########
########+------------------------------------------------------------+########
##############################################################################
##############################################################################
#########+--| Example 1 |-------------------------------------------+#########
#########| *    Flush data to a disk before any operation           |#########
#########| *    that could generate a fatal error.                  |#########
#########|                                                          |#########
#########| DO f_flush WITH output_file                              |#########
#########| DO do_calculation           && In case of a              |#########
#########|                             && divide by 0               |#########
#########|                             && error.                    |#########
#########+----------------------------------------------------------+#########
##############################################################################
##############################################################################
#########+--| Example 2 |-------------------------------------------+#########
#########| *    Flush data before running an external program       |#########
#########| *    through the RUN command in case of an error.        |#########
#########|                                                          |#########
#########| f_flush( text_file )                                     |#########
#########| RUN "x1drc.exe"                                          |#########
#########+----------------------------------------------------------+#########
##############################################################################